<html>
<head>
<title>Workflow Configuration</title>
<link href="book.css" rel="stylesheet" type="text/css"/>
<meta content="DocBook XSL Stylesheets V1.75.1" name="generator"/>
<link rel="home" href="index.html" title="Modeling Workflow Engine Reference"/>
<link rel="up" href="index.html" title="Modeling Workflow Engine Reference"/>
<link rel="prev" href="workflow_reference_included_workflow_components.html" title="Included Workflow Components"/>
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">Workflow Configuration</h1>
<div class="section" title="Workflow Configuration">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="workflow_reference_workflow_configuration"/>Workflow Configuration</h2>
</div>
</div>
</div>
<p>A workflow is wired up using an XML configuration language based on
    the dependency injection pattern (DI). Here is an example (not working,
    just an example!):</p>
<pre class="programlisting">&lt;workflow&gt;
	&lt;property name='genPath' value='/home/user/target'/&gt;
	&lt;property name='model' value='/home/user/model.xmi'/&gt;
	&lt;component class='org.eclipse.xtend.typesystem.emf.XmiReader'&gt;
		&lt;model value='${model}'/&gt;
	&lt;/component&gt;
	&lt;component class='org.eclipse.xtend.typesystem.xpand2.Generator'&gt;
		&lt;outlet&gt;
			&lt;path value='${genPath}'/&gt;
		&lt;/outlet&gt;
	&lt;/component&gt;
&lt;/workflow&gt;</pre>
<p>The root element is named <span class="emphasis">
<em>workflow</em>
</span>, then there
    are some property declarations followed by the declaration of two
    components.</p>
<p>Here is a tree representation of the resulting Java object
    graph:</p>
<div class="figure">
<a name="workflow_reference_java_object_graph"/>
<p class="title">
<b>Figure 1. Java Object Graph</b>
</p>
<div class="figure-contents">
<div class="mediaobject">
<img src="images/java_object_graph.GIF" width="534.6" alt="Java Object Graph"/>
</div>
</div>
</div>
<p>
<br class="figure-break"/> The configuration language expresses four different
    concepts:</p>
<div class="section" title="Properties">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="workflow_reference_properties"/>Properties</h3>
</div>
</div>
</div>
<p>Borrowing from Apache Ant, we use the concept of properties.
      Properties can be declared anywhere in a workflow file. They will be
      available after declaration.</p>
<p>We have two different kinds of properties</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>simple properties</p>
</li>
<li class="listitem">
<p>property files</p>
</li>
</ol>
</div>
<p>Here is an example:</p>
<pre class="programlisting">&lt;workflow&gt;
	&lt;property name='baseDir' value='./'/&gt;
	&lt;property file='${baseDir}/my.properties'/&gt;
	&lt;component
		class='my.Comp'
		srcDir='${baseDir}'
		modelName='${model}'
		pathToModel='${pathToModel}'/&gt;
&lt;/workflow&gt;</pre>
<p>First, there is a simple property <span class="property">baseDir</span>
      with the value "." defined. This property can be used in any attributes
      in the workflow file. The second property statement imports a property
      file. Property files use the well-known Java properties file syntax.
      There is one feature we added: You can use previously declared
      properties inside the properties file.</p>
<p>Example:</p>
<pre class="programlisting">model = myModel
pathToModel = ${baseDir}/${model}.xmi</pre>
<div class="section" title="Components">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="workflow_reference_components"/>Components</h4>
</div>
</div>
</div>
<p>The wired up object graph consists of so called components (A
        workflow component is a special kind of a component). A component is
        declared by an XML element. The name represents the property of the
        parent component holding this component.</p>
<p>Example:</p>
<pre class="programlisting">&lt;component class='MyBean'&gt;
	&lt;bean class='MyBean'/&gt;
&lt;/component&gt;</pre>
<p>The Java class MyBean needs to have a corresponding property
        accessor. E.g.:</p>
<pre class="programlisting">public class MyBean {
	...
	public void setBean(MyBean b) {
		bean = b;
	}
	...
}</pre>
<p>There are currently the following possibilities for declaring
        the property accessors:</p>
<div class="section" title="Accessor methods">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="workflow_reference_accessors"/>Accessor methods</h5>
</div>
</div>
</div>
<p>As we have seen, one possibility for declaring a dependency is
          to declare a corresponding setter Method.</p>
<pre class="programlisting">public void set&lt;propertyname&gt;(&lt;PropertyType&gt;; e)</pre>
<p>If you want to set multiple multiple values for the same
          property, you should define an adder method.</p>
<pre class="programlisting">public void add&lt;propertyname&gt;(&lt;PropertyType&gt; e)</pre>
<p>In some cases you may want to have key value pairs specified.
          This is done by providing the following method:</p>
<pre class="programlisting">public void put(Object k,Object v)</pre>
</div>
</div>
<div class="section" title="Component creation">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="workflow_reference_component_creation"/>Component creation</h4>
</div>
</div>
</div>
<p>The corresponding Java class (specified using the class
        attribute) needs to have a default constructor declared. If the class
        attribute is omitted, the Java class determined from the accessor
        method will be used. For the preceding example we could write</p>
<pre class="programlisting">&lt;component class='MyBean'&gt;
	&lt;bean/&gt;
&lt;/component&gt;</pre>
<p>because the setter method uses the <span class="type">MyBean</span> type as
        its parameter type. This is especially useful for more complex
        configurations of workflow components.</p>
<p>Note that we will probably add factory support in the
        future.</p>
</div>
<div class="section" title="References">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="workflow_reference_references"/>References</h4>
</div>
</div>
</div>
<p>A component can have an attribute <code class="varname">id</code>. If this
        is the case, we can refer to this component throughout the following
        workflow configuration.</p>
<p>Example:</p>
<pre class="programlisting">&lt;workflow&gt;
	&lt;component class='my.Checker'&gt;
		&lt;metaModel id='mm' class='my.MetaModel'
			metaModelPackage='org.eclipse.emf.mwe.metamodel'/&gt;
	&lt;/component&gt;
	&lt;component class='my.Generator'&gt;
		&lt;metaModel idRef='mm'/&gt;
	&lt;/component&gt;
	...
&lt;/workflow&gt;</pre>
<p>In this example, an object with the <span class="property">id</span>
        <span class="emphasis">
<em>mm</em>
</span> (an instance of
        <span class="emphasis">
<em>my.MetaModel</em>
</span>), is first declared and then
        referenced using the attribute <span class="property">idRef</span>. Note that
        this object will only be instantiated once and then reused. It is not
        allowed to specify any other attributes besides
        <span class="property">idRef</span> for object references.</p>
</div>
<div class="section" title="Simple Parameters">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="workflow_reference_simple_parameters"/>Simple Parameters</h4>
</div>
</div>
</div>
<p>Elements with only one attribute value are simple parameters.
        Simple parameters may not have any child elements.</p>
<p>Example:</p>
<pre class="programlisting">&lt;workflow&gt;
	&lt;component class='my.Checker' myParam='foo'&gt;
		&lt;anotherParam value='bar'/&gt;
	&lt;/component&gt;</pre>
<p>As you can see, there are two ways to specify a simple
        paramter.</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>using an XML attribute</p>
</li>
<li class="listitem">
<p>using a nested XML element with an attribute value</p>
</li>
</ol>
</div>
<p>Both methods are equivalent, although declaring an attribute way
        saves a few keystrokes. However, the attributes
        <code class="literal">class</code>, <code class="literal">id</code>, and
        <code class="literal">file</code> are reserved so they cannot be used.</p>
<p>Parameters are injected using the same accessor methods as
        described for components. The only difference is, that they are not
        instantiated using a default constructor, but instead, they are using
        a so-called converter.</p>
<div class="section" title="Converters">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="workflow_reference_converters"/>Converters</h5>
</div>
</div>
</div>
<p>There are currently converter implementations registered for
          the following Java types:</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>
<code class="classname">Object</code>
</p>
</li>
<li class="listitem">
<p>
<code class="classname">String</code>
</p>
</li>
<li class="listitem">
<p>
<code class="classname">String[]</code> (uses
              <code class="methodname">s.split(',')</code>)</p>
</li>
<li class="listitem">
<p>
<code class="classname">Boolean</code> (both primitive and
              wrapper)</p>
</li>
<li class="listitem">
<p>
<code class="classname">Integer</code> (both primitive and
              wrapper)</p>
</li>
</ol>
</div>
</div>
</div>
<div class="section" title="Including other workflow files (also known as cartridges)">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="workflow_reference_including_other_workflows"/>Including other workflow files (also known as
        <span class="emphasis">
<em>cartridges</em>
</span>)</h4>
</div>
</div>
</div>
<p>If an element has a property <span class="property">file</span>, it is
        handled as an inclusion. Using an inclusion, one can inject a graph
        described in another workflow file. Here is an example:</p>
<p>file 1: mybean.mwe</p>
<pre class="programlisting">&lt;anyname class='MyClass'/&gt;</pre>
<p>file 2: workflow.mwe</p>
<pre class="programlisting">&lt;comp class='MyBean'&gt;
	&lt;bean file='mybean.mwe'/&gt;
&lt;/comp&gt;</pre>
<p>One can pass properties and components into the included file in
        the usual way.</p>
<p>file 1: mybean.mwe</p>
<pre class="programlisting">&lt;anyname class='MyClass' aProp='${myParam}'&gt;
	&lt;bean idRef='myComponent'/&gt;
&lt;/anyname&gt;</pre>
<p>file 2: workflow.mwe</p>
<pre class="programlisting">&lt;comp class='MyBean'&gt;
	&lt;bean file='mybean.mwe'&gt;
		&lt;myParam value='foo'/&gt;
		&lt;myComponent class='MyBean'/&gt;
	&lt;/bean&gt;
&lt;/comp&gt;</pre>
<p>As you can see, simple parameters are mapped to properties in
        the included workflow file, and components can be accessed using the
        <span class="property">idRef</span> attribute.</p>
<p>Properties defined in the included workflow description will be
        overwritten by the passed properties.</p>
<p>The root element of a workflow description can have any name,
        because there is no parent defining an accessor method. Additionally,
        you have to specify the attribute class for a root element. There is
        only one exception: If the root element is named workflow the engine
        knows that it has to instantiate the type
        <code class="classname">org.eclipse.mwe.runtime.Workflow</code>. Of course
        you can specify your own subtype of
        <code class="classname">org.eclipse.mwe.runtime.Workflow</code> using the
        <span class="property">class</span> attribute (if you need to for any
        reason).</p>
</div>
<div class="section" title="InheritAll Feature">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="workflow_reference_inheritall"/>InheritAll Feature</h4>
</div>
</div>
</div>
<p>If you do not want to explicitely pass the parameters to an
        included workflow description, you can use the
        <span class="property">inheritAll</span> attribute. This will make all the
        properties and beans that are visible to the actual workflow file also
        visible to the included workflow file.</p>
<pre class="programlisting">&lt;component file="my/included/workflow.mwe" inheritAll="true"/&gt;</pre>
</div>
</div>
<div class="section" title="Component Implementation and Workflow Execution">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="workflow_reference_component_implementation"/>Component Implementation and Workflow Execution</h3>
</div>
</div>
</div>
<p>This section describes how to implement workflow components, how
      they can communicate with each other and how the workflow execution can
      be controlled.</p>
<div class="section" title="The Workflow Context">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="workflow_reference_context"/>The Workflow Context</h4>
</div>
</div>
</div>
<p>Workflow components have to communicate among each other. For
        example, if an XMIReader component reads a model that a constraint
        checker component wants to check, the model must be passed from the
        reader to the checker. The way this happens is as follows: In the
        <code class="methodname">invoke</code> operation, a workflow component has
        access to the so-called <span class="emphasis">
<em>workflow context</em>
</span>. This
        context contains any number of named slots. In order to communicate,
        two components agree on a slot name, the first component puts an
        object into that slot and the second component takes it from there.
        Basically, slots are named variables global to the workflow. The slot
        names are configured from the workflow file. Here is an
        example:</p>
<pre class="programlisting">&lt;?xml version="1.0" encoding="windows-1252"?&gt;
&lt;workflow&gt;
	&lt;property file="workflow.properties"/&gt;

	&lt;component id="xmiParser"
		class="org.eclipse.xtend.typesystem.emf.XmiReader"&gt;
		&lt;outputSlot value="model"/&gt;
	&lt;/component&gt;

	&lt;component id="checker" class="datamodel.generator.Checker"&gt;
		&lt;modelSlot value="model"/&gt;
	&lt;/component&gt;
&lt;/workflow&gt;</pre>
<p>As you can see, both these workflow components use the slot
        named <span class="emphasis">
<em>model</em>
</span>. Below is the (abbreviated)
        implementation of the <code class="classname">XmiReader</code>. It stores the
        model data structure into the workflow context in the slot whose name
        was configured in the workflow file.</p>
<pre class="programlisting">public class XmiReader implements WorkflowComponent {

	private String outputSlot = null;

	public void setOutputSlot(String outputSlot) {
		this.outputSlot = outputSlot;
	}

	public void invoke(WorkflowContext ctx, ProgressMonitor monitor,
		Issues issues) {
		Object theModel = readModel();
		ctx.put( outputSlot, theModel );
	}

}</pre>
<p>The checker component reads the model from that slot:</p>
<pre class="programlisting">public class Checker implements WorkflowComponent {

	private String modelSlot;

	public final void setModelSlot( String ms ) {
		this.modelSlot = ms;
	}

	public final void invoke(WorkflowContext ctx,
		ProgressMonitor monitor, Issues issues) {

		Object model = ctx.get(modelSlot);
		check(model);
	}
}</pre>
</div>
<div class="section" title="Issues">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="workflow_reference_issues"/>Issues</h4>
</div>
</div>
</div>
<p>Issues provide a way to report errors and warnings. There are
        two places, where issues are used in component implementations:</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>Inside the checkConfiguration operation, you can report
            errors or warnings. This operation is called before the workflow
            starts running.</p>
</li>
<li class="listitem">
<p>Inside the invoke operation, you can report errors or
            warnings that occur during the execution of the workflow. Typical
            examples are constraint violations.</p>
</li>
</ol>
</div>
<p>The Issues API is pretty straightforward: you can call addError
        and addWarning. The operations have three parameters: the reporting
        component, a message as well as the model element that caused the
        problem, if there is one. The operations are also available in a
        two-parameter version, omitting the first (reporting component)
        parameter.</p>
</div>
<div class="section" title="Controlling the Workflow">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="workflow_reference_controlling_workflow"/>Controlling the Workflow</h4>
</div>
</div>
</div>
<p>There is an implicit way of controlling the workflow: if there
        are errors reported from any of the checkConfiguration operations of
        any workflow component, the workflow will not start running.</p>
<p>There is also an explicit way of terminating the execution of
        the workflow: if any invoke operation throws a
        <code class="classname">WorkflowInterruptedException</code> (a runtime
        exception) the workflow will terminate immediately.</p>
<div class="section" title="Using Aspect Orientation wih Workflows">
<div class="titlepage">
<div>
<div>
<h5 class="title">
<a name="N10284"/>Using Aspect Orientation wih Workflows</h5>
</div>
</div>
</div>
<p>It is sometimes necessary to enhance existing workflow
          component declarations with additional properties. This is
          exemplified in the Template AOP example. To implement such an advice
          component, you have to extend the
          <code class="classname">AbstractWorkflowAdvice</code> class. You have to
          implement all the necessary getters and setters for the properties
          you want to be able to specify for that advice; also you have to
          implement the <code class="methodname">weave()</code> operation. In this
          operation, which takes the advised component as a parameter, you
          have to set the advised parameters:</p>
<pre class="programlisting">public class GeneratorAdvice extends AbstractWorkflowAdvice {

	private String advices;

	public String getAdvices() {
		return advices;
	}

	public void setAdvices(String advices) {
		this.advices = advices;
	}

	@Override
	public void weave(WorkflowComponent c) {
		Generator gen = (Generator)c;
		gen.setAdvices(advices);
	}

}</pre>
<p>In the workflow file, things are straight forward: You have to
          specify the component class of the advice, and use the special
          property <code class="varname">adviceTarget</code> to identify the target
          component:</p>
<pre class="programlisting">&lt;workflow&gt;

	&lt;cartridge file="workflow.mwe"/&gt;
		&lt;component adviceTarget="generator"
			class=".xpand2.GeneratorAdvice"&gt;
			&lt;advices value="templates::Advices"/&gt;
		&lt;/component&gt;
	&lt;/workflow&gt;</pre>
</div>
</div>
</div>
<div class="section" title="Invoking a workflow">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="workflow_reference_invoking_a_workflow"/>Invoking a workflow</h3>
</div>
</div>
</div>
<p>If you have described your generator process in a workflow file,
      you might want to run it. There are different possibilities for doing
      so.</p>
<div class="section" title="Starting the WorkflowRunner">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="workflow_reference_workflowrunner"/>Starting the WorkflowRunner</h4>
</div>
</div>
</div>
<p>The class
        <code class="classname">org.eclipse.emf.mwe.core.WorkflowRunner</code>
        is the main entry point if you want to run the workflow from the
        command line. Take a look at the following example:</p>
<pre class="programlisting">java org.eclipse.emf.mwe.core.WorkflowRunner path/workflow.mwe</pre>
<p>You can override properties using the -p option:</p>
<pre class="programlisting">java org.eclipse.emf.mwe.core.WorkflowRunner -pbasedir=/base/ path/workflow.mwe</pre>
</div>
<div class="section" title="Starting with Ant">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="workflow_reference_starting_with_ant"/>Starting with Ant</h4>
</div>
</div>
</div>
<p>We also have an Ant task. Here is an example:</p>
<pre class="programlisting">	&lt;target name='generate'&gt;
		&lt;taskdef name="workflow" classname="org.eclipse.emf.mwe.core.ant.WorkflowAntTask"/&gt;
			&lt;workflow file='path/workflow.mwe'&gt;
				&lt;param name='baseDir' value='/base/'/&gt;
			&lt;/workflow&gt;
			...
		&lt;/target&gt;</pre>
<p>The Workflow ant task extends the Java ant task. Therefore, you
        have all the properties known from that task (classpath, etc.).</p>
</div>
<div class="section" title="Starting from you own code">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="workflow_reference_starting_from_your_own_code"/>Starting from you own code</h4>
</div>
</div>
</div>
<p>You can also run the generator from your own application code.
        Two things to note:</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>the contents of the properties map override the properties
            defined in the workflow.</p>
</li>
<li class="listitem">
<p>The slotContents map allows you to fill stuff into the
            workflow from your application. This is a typical use case: you
            run MWE from within your app because you already have a model in
            memory.</p>
</li>
</ol>
</div>
<pre class="programlisting">	String wfFile = "somePath\\workflow.mwe";
	Map properties = new HashMap();
	Map slotContents = new HashMap();
	new WorkflowRunner().run(wfFile ,
		new NullProgressMonitor(), properties, slotContents)</pre>
</div>
<div class="section" title="Starting from Eclipse">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="N102C6"/>Starting from Eclipse</h4>
</div>
</div>
</div>
<p>You can also run a workflow file from within Eclipse if you have installed the
          MWE plugins. Just right-click on the workflow file
          (<code class="filename">whatever.mwe</code>) and select <span class="guimenu">Run
          As</span> → <span class="guimenuitem">MWE Workflow</span>. See
          the section <span class="emphasis">
<em>
<span>
<a class="xref" href="">???</a>
</span> <span>Running a workflow</span>
</em>
</span> in the
          documentation of the Eclipse integration of MWE for details.</p>
</div>
</div>
</div>
</body>
</html>
